docs(skills): improve drafting skills from signal log patterns 2026-08-05 - #478

Patterns addressed

Signal window: last 30 days (through 2026-08-05). Primary source: GitHub human review comments and verdicts on agent-coauthored merged PRs, plus the durable log on chore/drafting-signal-logs. Oz run style-lint and pr-review signal markers were not present in title-matched runs from oz run list --limit 100 (CLI has no pagination cursor on this build).

1. missing_media / screenshots for visual UI (human feedback: review comments across 6 PRs, including docs: Warp Agent CLI launch documentation #411, docs(cli): cloud handoff and orchestration #402, docs: publish Jira integration page with self-serve setup flow #338, docs(APP-4267): add Mermaid diagrams section to Markdown Viewer #305)

   • Reviewers repeatedly asked to add screenshots for surfaces agents described only in prose (statusline chips, Agents tab bar, settings chrome).
   • Existing rules covered alt text and “don’t screenshot the obvious,” but not when a screenshot is required.
   • Signal type: repeated human review comment across multiple PRs (threshold: 2+ PRs).

2. VideoEmbed title prop (human + template gap; guide template previously omitted title)

   • AGENTS.md already requires a specific title on every VideoEmbed, but guide-page.md scaffolded embeds without title, and step 6.5 had no concrete good/bad example.
   • Drafting agents copy the template and ship title-less embeds.
   • Signal type: template gap reinforced by style-guide requirement and review traffic on video pages (for example docs: update team-managed keys demo video #326 and docs: add dedicated Computer Use testing and video recordings page #374).

Improvement targets

• .agents/skills/draft_docs/SKILL.md — additive Critical formatting rules + checklist items for screenshot inclusion and VideoEmbed titles (shared by all drafting skills)
• .agents/templates/feature-doc.md — bracket instruction to place screenshots after the prose that introduces distinctive visual surfaces
• .agents/templates/guide-page.md — require a specific title prop on the scaffolded VideoEmbed (or remove the block)

Patterns reviewed but not acted on

• callout / settings_path / content_structure / image_alt — already proposed in open PR docs(skills): improve drafting skills from signal log patterns 2026-08-01 #450
• ui_label_accuracy / durable UI / availability honesty / Related pages — already proposed in open PR docs(skills): improve drafting skills from signal log patterns 2026-08-03 #454
• heading_specificity / frontmatter / list_format / link_quality — already proposed in open PR docs(skills): improve drafting skills from signal log patterns 2026-08-04 #468
• terminology (23 PRs) — already covered by glossary + product-name variables in step 6.5; remaining hits were page-specific naming accuracy
• scannability (11 PRs) — already has checklist item for dense sections; remaining hits were page-specific tightening
• code_fence (3 PRs) — mostly false positives from GitHub suggestion-review blocks, not missing language identifiers
• feature_status_accuracy (4 PRs) — partially covered by open PR docs(skills): improve drafting skills from signal log patterns 2026-08-03 #454 availability-honesty guidance

Open questions for human review

1. Is “screenshot or explicit note that none is available yet” the right bar for agent-authored PRs when the agent cannot capture UI in CI?
2. Should style_lint grow a video_embed_title check so title-less embeds fail automatically, or is the skill/template guidance enough?

Test plan

• git diff --check clean
• YAML frontmatter parse check on changed skill/template files
• Diff limited to .agents/skills/ and .agents/templates/
• Edits are additive (no removals of existing rules)

Related

• Standing signal-log PR: chore: drafting signal logs #467
• Prior open improvement PRs (do not duplicate): docs(skills): improve drafting skills from signal log patterns 2026-08-01 #450, docs(skills): improve drafting skills from signal log patterns 2026-08-03 #454, docs(skills): improve drafting skills from signal log patterns 2026-08-04 #468